The 640 MEG Shareware Studio 2/The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO/os2/isp3009b.zip/ISPELL4.DOC

Text File | 1992-09-08 | 25KB | 540 lines

   local                                                            ISPELL(4)



   NAME
     ispell - format of ispell dictionaries and affix files

   DESCRIPTION

     Ispell(1) requires two files to define the language that it is spell-
     checking.  The first file is a dictionary containing words for the
     language, and the second is an "affix" file that defines the meaning of
     special flags in the dictionary.  The two files are combined by buil-
     dhash (see ispell(1)) and written to a hash file which is not described
     here.

     A raw ispell dictionary (either the main dictionary or your own personal
     dictionary) contains a list of words, one per line.  Each word may
     optionally be followed by a slash ("/") and one or more flags, which
     modify the root word as explained below.  Depending on the options with
     which ispell was built, case may or may not be significant in either the
     root word or the flags, independently.  Specifically, if the compile-
     time option CAPITALIZATION is defined, case is significant in the root
     word; if not, case is ignored in the root word.  If the compile-time
     option MASKBITS is set to a value of 32, case is ignored in the flags;
     otherwise case is significant in the flags.  Contact your system
     administrator or ispell maintainer for more information (or just experi-
     ment).  The dictionary should be sorted with the -f flag of sort(1)
     before the hash file is built; this is done automatically by mun-
     chlist(1), which is the normal way of building dictionaries.

     The case of the root word controls the case of words accepted by ispell,
     as follows:

     (1)  If the root word appears only in lower case (e.g., bob), it will be
          accepted in lower case, capitalized, or all capitals.

     (2)  If the root word appears capitalized (e.g., Robert), it will not be
          accepted in all-lower case, but will be accepted capitalized or all
          in capitals.

     (3)  If the root word appears all in capitals (e.g., UNIX), it will only
          be accepted all in capitals.

     (4)  If the root word appears with a "funny" capitalization (e.g.,
          ITCorp), a word will be accepted only if it follows that capitali-
          zation, or if it appears all in capitals.

     (5)  More than one capitalization of a root word may appear in the dic-
          tionary.  Flags from different capitalizations are combined by OR-
          ing them together.

     Redundant capitalizations (e.g., bob and Bob) will be combined by buil-
     dhash and by ispell (for personal dictionaries), and can be removed from
     a raw dictionary by munchlist.

     For example, the dictionary:

          bob
          Robert
          UNIX
          ITcorp
          ITCorp

     will accept bob, Bob, BOB, Robert, ROBERT, UNIX, ITcorp, ITCorp, and
     ITCORP, and will reject all others.  Some of the unacceptable forms are
     bOb, robert, Unix, and ItCorp.

     As mentioned above, root words in any dictionary may be extended by
     flags.  Each flag is a single alphabetic character, which represents a
     prefix or suffix that may be added to the root to form a new word.  For
     example, in an English dictionary the D flag can be added to bathe to
     make bathed.  Since flags are represented as a single bit in the hashed
     dictionary, this results in significant space savings.  The munchlist
     script will reduce an existing raw dictionary by adding flags when pos-
     sible.

     When a word is extended with an affix, the affix will be accepted only
     if it appears in the same case as the initial (prefix) or final (suffix)
     letter of the word.  Thus, for example, the entry UNIX/M in the main
     dictionary (M means add an apostrophe and an "s" to make a possessive)
     would accept UNIX'S but would reject UNIX's.  If UNIX's is legal, it
     must appear as a separate dictionary entry, and it will not be combined
     by munchlist.  (In general, you don't need to worry about these things;
     munchlist guarantees that its output dictionary will accept the same set
     of words as its input, so all you have to do is add words to the dic-
     tionary and occasionally run munchlist to reduce its size).

     As mentioned, the affix definition file describes the affixes associated
     with particular flags.  It also describes the character set used by the
     language.

     Although the affix-definition grammar is designed for a line-oriented
     layout, it is actually a free-format yacc grammar and can be laid out
     weirdly if you want.  Comments are started by a pound (sharp) sign (#),
     and continue to the end of the line.  Backslashes are supported in the
     usual fashion (\nnn, plus specials \n, \r, \t, \v, \f, \b, and the new
     hex format \xnn).  Any character with special meaning to the parser can
     be changed to an uninterpreted token by backslashing it; for example,
     you can declare a flag named flag \*: or flag \::.

     The grammar will be presented in a top-down fashion, with discussion of
     each element.  An affix-definition file must contain exactly one table:

          table     :    [headers] [prefixes] [suffixes]

     At least one of prefixes and suffixes is required.  They can appear in
     either order.

          headers   :    [ options ] char-sets

     The headers describe options global to this dictionary and language.
     These include the character sets to be used and the formatter, and the
     defaults for certain ispell flags.

          options   :    { fmtr-stmt | bool-stmt | flag-stmt }

     The options statements define the defaults for certain ispell flags and
     for the character sets used by the formatters.

          fmtr-stmt :    { nroff-stmt | tex-stmt }

     A fmtr-stmt describes characters that have special meaning to a for-
     matter.  Normally, this statement is not necessary, but some languages
     may have preempted the usual defaults for use as language-specific char-
     acters.  In this case, these statements may be used to redefine the spe-
     cial characters expected by the formatter.

          nroff-stmt     :    { nroffchars | troffchars } string

     The nroffchars statement allows redefinition of certain nroff control
     characters.  The string given must be exactly five characters long, and
     must list substitutions for the left and right parentheses ("()") , the
     period ("."), the backslash ("\"), and the asterisk ("*").  (The right
     parenthesis is not currently used, but is included for completeness.)
     For example, the statement:

          nroffchars {}.\\*
     would replace the left and right parentheses with left and right curly
     braces for purposes of parsing nroff/troff strings, with no effect on
     the others (admittedly a contrived example).  Note that the backslash is
     escaped with a backslash.

          tex-stmt  :    { TeXchars | texchars } string

     The TeXchars statement allows redefinition of certain TeX/LaTeX control
     characters.  The string given must be exactly thirteen characters long,
     and must list substitutions for the left and right parentheses ("()") ,
     the left and right square brackets ("[]"), the left and right curly
     braces ("{}"), the left and right angle brackets ("<>"), the backslash
     ("\"), the dollar sign ("$"), the asterisk ("*"), the period or dot
     ("."), and the percent sign ("%").  For example, the statement:

          texchars ()\[]<\><\>\\$*.%

     would replace the functions of the left and right curly braces with the
     left and right angle brackets for purposes of parsing TeX/LaTeX con-
     structs, while retaining their functions for the tib bibliographic
     preprocessor.  Note that the backslash, the left square bracket, and the
     right angle bracket must be escaped with a backslash.

          bool-stmt :    { cmpnd-stmt | aff-stmt }

          cmpnd-stmt     :    compoundwords on-or-off

          aff-stmt       :    allaffixeson-or-off

          on-or-off :    { on | off }

     A bool-stmt controls certain ispell defaults that are best made
     language-specific.  The allaffixes statement controls the default for
     the -P and -m options to ispell. If allaffixes is turned off (the
     default), ispell will default to the behavior of the -P flag: root/affix
     suggestions will only be made if there are no "near misses".  If allaf-
     fixes is turned on, ispell will default to the behavior of the -m flag:
     root/affix suggestions will always be made.  The compoundwords statement
     controls the default for the -B and -C options to ispell. If compound-
     words is turned off (the default), ispell will default to the behavior
     of the -B flag: run-together words will be reported as errors.  If com-
     poundwords is turned on, ispell will default to the behavior of the -C
     flag: run-together words will be considered as compounds if both are in
     the dictionary.  This is useful for languages such as German and
     Norwegian, which form large numbers of compound words.

          flag-stmt :    flagmarker character

     The flagmarker statement describes the character which is used to
     separate affix flags from the root word in a raw dictionary file.  This
     must be a character which is not found in any word (including in string
     characters; see below).  The default is "/" because this character is
     not normally used to represent special characters in any language.

          char-sets :    norm-sets [ alt-sets ]

     The character-set section describes the characters that can be part of a
     word, and defines their collating order.  There must always be a defini-
     tion of "normal" character sets;  in addition, there may be one or more
     partial definitions of "alternate" sets which are used with various text
     formatters.

          norm-sets :    [ deftype ] charset-group

     A "normal" character set may optionally begin with a definition of the
     file suffixes that make use of this set.  Following this are one or more
     character-set declarations.

          deftype : defstringtype name suffix*

     The defstringtype declaration gives a list of file suffixes which should
     make use of the default string characters defined as part of the base
     character set; it is only necessary if string characters are being
     defined.  The name is a string giving the name associated with these
     suffixes; usually it is a formatter name.  If the formatter is a member
     of the troff family, "nroff" should be used for the name associated with
     the most popular macro package; members of the TeX family should use
     "tex".  Other names may be chosen freely, but they should be kept sim-
     ple, as they are used in ispell 's -T switch to specify a formatter
     type.  The suffixes are a whitespace-separated list of strings which, if
     present at the end of a filename, indicate that the associated set of
     string characters should be used by default for this file.  For example,
     the suffix list for the troff family typically includes suffixes such as
     ".ms", ".me", ".mm", etc.

          charset-group :     { char-stmt | string-stmt | dup-stmt}*

     A char-stmt describes single characters; a string-stmt describes charac-
     ters that must appear together as a string, and which usually represent
     a single character in the target language.  Either may also describe
     conversion between upper and lower case.  A dup-stmt is used to describe
     alternate forms of string characters, so that a single dictionary may be
     used with several formatting programs that use different conventions for
     representing non-ASCII characters.

          char-stmt :    wordchars character-range
                    |    wordchars lowercase-range uppercase-range
                    |    boundarychars character-range
                    |    boundarychars lowercase-range uppercase-range
          string-stmt    :    stringchar string
                    |    stringchar lowercase-string uppercase-string

     Characters described with the boundarychars statement are considered
     part of a word only if they are embedded between characters declared
     with the wordchars or stringchar statements.

     If two ranges or strings are given in a char-stmt or string-
     stmt,thefirstdescribes characters that are interpreted as lowercase and
     the second describes uppercase.  In the case of a stringchar statement,
     the two strings must be of the same length.  Also, in a stringchar
     statement, the actual strings may contain both uppercase and characters
     themselves without difficulty; for instance, the statement

          stringchar     "\\*(sS"  "\\*(Ss"

     is legal and will not interfere with (or be interfered with by) other
     declarations of of "s" and "S" as lower and upper case, respectively.

     A final note on string characters: some languages collate certain spe-
     cial characters as if they were strings.  For example, the German "a-
     umlaut" is traditionally sorted as if it were "ae".  Ispell is not capa-
     ble of this; each character must be treated as an individual entity.  So
     in certain cases, ispell will sort a list of words into a different
     order than the standard "dictionary" order for the target language.

          alt-sets  :    alttype alt-stmt*

     Because different formatters use different notations to represent non-
     ASCII characters, ispell must be aware of the representations used by
     these formatters.  These are declared as alternate sets of string char-
     acters.

          alttype   :    altstringtype name suffix*

     The altstringtype statement introduces each set by declaring the associ-
     ated formatter name and filename suffix list.  This name and list are
     interpreted exactly as in the defstringtype statement above.  Following
     this header are one or more alt-stmts which declare the alternate string
     characters used by this formatter.

          alt-stmt       :    altstringchar alt-string std-string
     The altstringchar statement describes alternate representations for
     string characters.  For example, the -mm macro package of troff
     represents the German "a-umlaut" as a\*:,while TeX uses the sequence
     \"a.  If the troff versions are declared as the standard versions using
     stringchar, the TeX versions may be declared as alternates by using the
     statement

          altstringchar  \\\"a     a\\*

     When the altstringchar statement is used to specify alternate forms, all
     forms for a particular formatter must be declared together as a group.
     Also, each formatter or macro package must provide a complete set of
     characters, both upper- and lower-case, and the character sequences used
     for each formatter must be completely distinct.  Character sequences
     which describe upper- and lower-case versions of the same printable
     character must also be the same length.  It may be necessary to define
     some new macros for a given formatter to satisfy these restrictions.
     (The current version of buildhash does not enforce these restrictions,
     but failure to obey them may result in errors being introduced into
     files that are processed with ispell.)

     An important minor point is that ispell assumes that all characters
     declared as wordchars or boundarychars will occupy exactly one position
     on the terminal screen.

     A single character-set statement can declare either a single character
     or a contiguous range of characters.  A range is given as in egrep and
     the shell: [a-z] means lowercase alphabetics; [^a-z] means all but
     lowercase, etc.  All character-set statements are combined (unioned) to
     produce the final list of characters that may be part of a word.  The
     collating order of the characters is defined by the order of their
     declaration; if a range is used, the characters are considered to have
     been declared in ASCII order.  Characters that have case are collated
     next to each other, with the uppercase character first.

     The character-declaration statements have a rather strange behavior
     caused by its need to match each lowercase character with its uppercase
     equivalent.  In any given wordchars or boundarychars statement, the
     characters in each range are first sorted into ASCII collating sequence,
     then matched one-for-one with the other range.  (The two ranges must
     have the same number of characters).  Thus, for example, the two state-
     ments:

          wordchars [aeiou] [AEIOU]
          wordchars [aeiou] [UOIEA]

     would produce exactly the same effect.  To get the vowels to match up
     "wrong", you would have to use separate statements:

          wordchars a U
          wordchars e O
          wordchars i I
          wordchars o E
          wordchars u A

     which would cause uppercase 'e' to be 'O', and lowercase 'O' to be 'e'.
     This should normally be a problem only with languages which have been
     forced to use a strange ASCII collating sequence.  If your uppercase and
     lowercase letters both collate in the same order, you shouldn't have to
     worry about this "feature".

     The prefixes and suffixes sections have exactly the same syntax, except
     for the introductory keyword.

          prefixes  :    prefixes flagdef*
          suffixes  :    suffixes flagdef*
          flagdef   :    flag [*] char : repl*

     A prefix or suffix table consists of an introductory keyword and a list
     of flag definitions.  Flags can be defined more than once, in which case
     the definitions are combined.  Each flag controls one or more repls
     (replacements) which are conditionally applied to the beginnings or end-
     ings of various words.

     Flags are named by a single character char.  Depending on a configura-
     tion option, this character can be either any uppercase letter (the
     default configuration) or any 7-bit ASCII character.  Most languages
     should be able to get along with just 26 flags.

     If an asterisk (*) is placed before the flag character, it means that
     this flag participates in cross-product formation.  This only matters if
     the file contains both prefix and suffix tables.  If so, all prefixes
     and suffixes marked with an asterisk will be applied in all cross-
     combinations to the root word.  For example, consider the root fix with
     prefixes pre and in, and suffixes es and ed.  If all flags controlling
     these prefixes and suffixes are marked with an asterisk, then the single
     root fix would also generate prefix, prefixes, prefixed, infix, infixes,
     infixed, fix, fixes, and fixed.  Cross-product formation can produce a
     large number of words quickly, some of which may be illegal, so watch
     out.  If cross-products produce illegal words, munchlist will not pro-
     duce those flag combinations, and the flag will not be useful.

          repl :    condition* > [ - strip-string , ] append-string

     A repl is a conditional rule for modifying a root word.  Up to 8 condi-
     tions may be specified.  If the conditions are satisfied, the rules on
     the right-hand side of the repl are applied, as follows:

     (1)  If a strip-string is given, it is first stripped from the beginning
          or ending (as appropriate) of the root word.

     (2)  Then the append-string is added at that point.

     For example, the condition . means "any word", and the condition Y means
     "any word ending in Y".  The following (suffix) replacements:

          Y    >    -Y,IES

     would change induce to inducement and fly to flies.  (If they were con-
     trolled by the same flag, they would also change fly to flyment, which
     might not be what was wanted.  Munchlist can be used to protect against
     this sort of problem; see the command sequence given below.)

     No matter how much you might wish it, the strings on the right must be
     strings of specific characters, not ranges.  The reasons are rooted dee-
     ply in the way ispell works, and it would be difficult or impossible to
     provide for more flexibility.  For example, you might wish to write:

          [EY] >    -[EY],IES

     This will not work.  Instead, you must use two separate rules:

          E    >    -E,IES
          Y    >    -Y,IES

     The application of repls can be restricted to certain words with condi-
     tions:

          condition :    { . | character | range }

     A condition is a restriction on the characters that adjoin, and/or are
     replaced by, the right-hand side of the repl.  Up to 8 conditions may be
     given, which should be enough context for anyone.  The right-hand side
     will be applied only if the conditions in the repl are satisfied.  The
     conditions also implicitly define a length; roots shorter than the
     number of conditions will not pass the test.  (As a special case, a con-
     dition of a single dot "." defines a length of zero, so that the rule
     applies to all words indiscriminately).  This length is independent of
     the separate test that insists that all flags produce an output word
     length of at least four.

     Conditions that are single characters should be separated by white
     space.  For example, to specify words ending in "ED", write:

          E D  >    -ED,ING        # As in covered > covering

     If you write:

          ED   >    -ED,ING

     the effect will be the same as:

          [ED] >    -ED,ING

     As a final minor, but important point, it is sometimes useful to rebuild
     a dictionary file using an incompatible suffix file.  For example, sup-
     pose you expanded the "R" flag to generate "er" and "ers" (thus making
     the Z flag somewhat obsolete).  To build a new dictionary newdict that,
     using newaffixes, will accept exactly the same list of words as the old
     list olddict did using oldaffixes, the -c switch of munchlist is useful,
     as in the following example:

          $ munchlist -c oldaffixes -l newaffixes olddict > newdict

     If you use this procedure, your new dictionary will always accept the
     same list the original did, even if you badly screwed up the affix file.
     This is because munchlist compares the words generated by a flag with
     the original word list, and refuses to use any flags that generate ille-
     gal words.  (But don't forget that the munchlist step takes a long time
     and eats up temporary file space).

   EXAMPLES

     As an example of conditional suffixes, here is the specification of the
     S flag from the English affix file:

          flag *S:
              [^AEIOU]Y  >    -Y,IES    # As in imply > implies
              [AEIOU]Y   >    S         # As in convey > conveys
              [SXZH]     >    ES        # As in fix > fixes
              [^SXZHY]   >    S         # As in bat > bats

     The first line applies to words ending in Y, but not in vowel-Y.  The
     second takes care of the vowel-Y words.  The third then handles those
     words that end in a sibilant or near-sibilant, and the last picks up
     everything else.

     Note that the conditions are written very carefully so that they apply
     to disjoint sets of words.  In particular, note that the fourth line
     excludes words ending in Y as well as the obvious SXZH.  Otherwise, it
     would convert "imply" into "implys".

     Although the English affix file does not do so, you can also have a flag
     generate more than one variation on a root word.  For example, we could
     extend the English "R" flag as follows:

          flag *R:
             E           >    R         # As in skate > skater
             E           >    RS        # As in skate > skaters
             [^AEIOU]Y   >    -Y,IER    # As in multiply > multiplier
             [^AEIOU]Y   >    -Y,IERS   # As in multiply > multipliers
             [AEIOU]Y    >    ER        # As in convey > conveyer
             [AEIOU]Y    >    ERS       # As in convey > conveyers
             [^EY]       >    ER        # As in build > builder
             [^EY]       >    ERS       # As in build > builders

     This flag would generate both "skater" and "skaters" from "skate".  This
     capability can be very useful in languages that make use of noun, verb,
     and adjective endings.  For instance, one could define a single flag
     that generated all of the German "weak" verb endings.

   SEE ALSO
     ispell1.doc








































   10